|   File        : !Help
|   Date        : 17-Jun-03
|
|   Copyright  1993, 2003 Alexander Thoukydides
|
|   This program is free software; you can redistribute it and/or
|   modify it under the terms of the GNU General Public License
|   as published by the Free Software Foundation; either version 2
|   of the License, or (at your option) any later version.
|
|   This program is distributed in the hope that it will be useful,
|   but WITHOUT ANY WARRANTY; without even the implied warranty of
|   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|   GNU General Public License for more details.
|
|   You should have received a copy of the GNU General Public License
|   along with this program; if not, write to the Free Software
|   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

File list
~~~~~~~~~
!DeskStart
    !Boot ............ loads sprites and sets up system variables and aliases
    !Run ............. executed when !DeskStart is run
    TempA43D ......... small templates for A4 portable
    TemplOld3D ....... old style 3D WIMP templates
    TemplNew3D ....... new style 3D WIMP templates
    Templates ........ WIMP templates to be used
    !Sprites ......... sprite file
    !RunImage ........ main program
    !Config .......... configuration data
    !Help ............ this file
    GPL .............. copy of the GNU General Public License
    Messages ......... textual messages used by the program

On a machine fitted with RISC OS 2 or 3 this application also requires the
Interface Manager module (version 2.00 or above) by SoftWare Interrupt
Developments to be placed in the !System.Modules directory. This is supplied
with many public domain applications.

On a machine fitted with RISC OS 2, it is also necessary to place the
MessageTrans module (version 0.03 or above) in the !System.Modules directory.
This may be obtained from many sources, such as with the later versions of
the RISC OS 2 printer drivers.

Introduction
~~~~~~~~~~~~
!DeskStart performs a similar function to *DeskTop -file. The main difference
is that each task is allowed to start-up fully before the next is started,
and a limited degree of multi-tasking is available. The original reason for
this program was to enable something more interesting than a blank grey
screen to be shown while a lengthy start-up sequence is performed. Since then
many other facilities have been added (see below), including a status window
and a percentage completed display.

Two types of file are used by the program:
    &3F0 (DeskStrt) - A script file containing commands to be executed
(created by the user)
    &FFF (Text) - A file containing timing information used internally by the
program (created by !DeskStart).

The DeskStrt filetype was allocated by Acorn. It should not, therefore, clash
with any other application. If, however, this filetypes does cause a clash on
a particular system, it may be changed by editing the !Boot, !Run and
!Sprites files. There is no need to alter the main program code as the type
is accessed by the textual description rather than numerically. The
application name "!DeskStart" and the command "DeskStart" were also reserved
by Acorn for exclusive use by this application. If a problem is encountered
with any of these, please contact the author so that a proper solution may be
found.

Usage
~~~~~
The simplest method of using !DeskStart is to use *!DeskStart <filename>,
where !DeskStart is in the current search path (Run$Path) and <filename> is
the complete pathname of a DeskStrt file (see below for details). A better
approach is to run the !Boot file within the !DeskStart application
directory, or open the parent directory viewer if the desktop has already
been started. This has the effect of setting an alias for *DeskStart
<filename> to enter the desktop (if it has not already been started) and run
!DeskStart with the named DeskStrt file. It also defines the DeskStrt file
type, loads its sprite, and sets its run action.

After execution of a DeskStrt file, a timings file is generated. It is saved
in the same directory as the original DeskStrt file, but with a "t" suffix
(so the DeskStrt file must have a shorter filename than the maximum length
allowed). This file must not be edited by the user. The next time the
DeskStrt file is run, the timings file is looked for, and compared with the
DeskStrt file being executed. If the file exists, and the contents match the
DeskStrt file, it is used to give an indication of how long the commands will
take to be executed. The program will normally be able to tell if the
DeskStrt file has changed since the timings file was created, but it is
possible to force !DeskStart to generate a new timings file by deleting the
existing one. If !DeskStart is unable to create a timings file (DeskStrt file
has too long a name, or old timings file is locked), a warning is given
before the program quits. 

Status window
~~~~~~~~~~~~~
The status window is opened automatically by !DeskStart when it is run, and
may be opened or closed by commands in the DeskStrt file. Clicking with
SELECT or ADJUST on the icon-bar icon will also open or close the status
window. At the top of the window is a line which shows the current command
being executed, or other text specified in the DeskStrt file (see Echo,
EchoOn, EchoOff below). Below this is a bar which indicates how far through
the DeskStrt file the program is. The solid bar shows the approximate
fraction of the total time taken so far. This value is also shown as a
percentage to the right of the bar. The hollow bar shows the time that the
next/current command will take. Note that these features are dependent upon
the existence of a valid timings file, and that if no suitable file is
present the program will assume an equal time for each command, and create a
timings file for the next use of the DeskStrt file.

There are six buttons at the bottom of the window. These control execution of
the DeskStrt file.

    Suspend: This is only available when the DeskStrt file is being executed.
When this button is clicked on, DeskStrt file execution is suspended. While
suspended, the status icon shows the next command to be executed, regardless
of whether echo is on or off.

    Resume: This continues execution of the DeskStrt file after it has been
suspended. The echo status is set to the value that it was at before
execution was suspended. If there are no more commands to be executed, this
causes the program to exit normally - saving a new timings file if valid
timing data has been generated.

    Single: This executes a single instruction from the DeskStrt file.

    Skip: This skips the current instruction, and goes onto the next. Using
this function may prevent the production of a timings file as the program has
no way of knowing how long the command should take.

    Faster: This executes the DeskStrt file quicker, by reducing the amount
of multi-tasking and screen update that occurs. Note that the red bar is only
updated when the textual status is altered.

    Abort: This abandons the DeskStrt file, and terminates the program
without saving a timings file.

The function keys F1 to F6 behave the same as clicking on the corresponding
icon, i.e. F1 activates Suspend, F2 activates Resume etc. The space bar
toggles paused mode (see the command Pause below). Note that these keys only
have an effect when the status window is open, and no other application grabs
the keys.

The status window provides interactive help via the Acorn !Help application.

Menus
~~~~~
Clicking Menu over the icon bar icon generates a menu with the following items:

    Info     About this program ....... Details of this program
    Control  Suspend .................. Same as clicking on the Suspend icon
              Resume ................... Same as clicking on the Resume icon
    Step     Single ................... Same as clicking on the Single icon
              Skip ..................... Same as clicking on the Skip icon
    Faster ............................. Same as clicking on the Faster icon
    Quit ............................... Same as clicking on the Abort icon

Clicking Menu over the status window generates a menu with the following item:

    Info     About this program ....... Details of this program

Clicking Menu over the "About this program" window, or clicking on the icon
at the bottom, opens a new window giving information about the author.

DeskStrt files
~~~~~~~~~~~~~~
The DeskStrt file should contain ASCII text, one command per line. Leading
spaces are stripped during execution. Blank lines and those starting with the
"|" character are ignored. Lines starting with the "%" character are taken to
be internal commands, used to control the operation of !DeskStart, and these
are listed later. The commands may be in upper or lower case (or a mixture of
both), and may contain any (non-zero) number of spaces to separate
parameters.

Normally all commands are echoed in the status window, but this may be
controlled using the %EchoOff and %EchoOn commands. Any command may be
prefixed by an "@" character to prevent it being displayed in the status
window when echo is on. For internal commands the "@" character must come
before the "%".

Any lines not starting with a "|" or "%" or "@%" are executed by a WimpTask
command.

The possible internal commands are:

    Close: Close the status window.

    Echo <text>: Display the specified text string (which must only contain
printable characters, not control codes) in the status window. The string is
passed to OS_GSTrans before display, so may include system variables. Note
that this command also turns echo off, otherwise the message will be
overwritten immediately by the next command.

    EchoOff: Prevents echoing of commands in the status window. This takes
effect from the next command. To prevent this command itself being echoed it
must be prefixed by an "@" character.

    EchoOn: Reset the echo status to its default of being on. This takes
effect from the next command.

    Include <file>: This command is different from all the others in that it
is performed before the start of execution of the DeskStrt file. It has the
effect of including all the commands from the named file at the current
location in the current file. Neither DeskStrt file is altered by this
command, but the commands from both files are listed in the single timings
file, and hence changes to either file will result in the timings being
invalid. No error or message is given if the file does not exist. This
command is useful where multiple DeskStrt files are used, but a common
section is required.

    Open: Open the status window in front of all other windows, at its
previous location.

    OpenAt <xpos> <ypos>: Open the status window in front of all other
windows, at the specified location. The parameters <xpos> and <ypos> must be
of the form L|B|C|M|R|T[+|-<integer>]. There must be no spaces within an
expression, as spaces are used to separate parameters. The letters "L" and
"B" represent the left or bottom of the screen, the letters "C" and "M" the
centre, and the letters "R" and "T" the right or top. The optional plus or
minus a constant allows the window position to be specified relative to one
of the nine main positions, e.g. %OpenAt C T-32 will open the window at the
centre of the screen, 32 OS coordinates down from the top of the screen.

    Pause: Pause execution of the DeskStrt file. This is similar to the
Suspend command except that the single stepping options are not available,
and the echo status is maintained.

    Speed <polls>: Change number of Wimp_Polls performed between each
command. If <polls> is set to 0, a single Wimp_Poll will be performed
inbetween commands, but less screen update will occur than if <polls> was set
to 1 (this is equivalent to the user clicking on the Faster icon). The
maximum allowable setting of <polls> is 128.

    Suspend: Suspend execution of the DeskStrt file. This performs the same
action as the user clicking on the Suspend icon in the status window (see
above).

Note that the status window is initially opened when the first output is
produced. This is normally caused by the first command in the DeskStrt file.
To prevent this, the first command must be prefixed by an "@" character. An
example DeskStrt file follows:

    |   File        : DestStrt
    |   Date        : 12-Jun-03
    |
    |   Copyright  1993, 2003 Alexander Thoukydides
    @%EchoOff
    %OpenAt L+16 T-16
    %Echo Initialising
    Run !System.!Boot
    Run !Fonts.!Boot
    %Echo Finished!

This file starts by switching off the automatic echoing of commands, and is
prefixed by an "@" character, so the status window is not opened
automatically. The next command opens the status window near the top left of
the screen. The next command displays the message "Initialising". The next
two commands are passed to WimpTask and initialise the system utilities and
font manager. The message "Finished!" is then displayed.

Customisation
~~~~~~~~~~~~~
It is possible to customise some aspects of the operation of !DeskStart. The
main way of doing this is to alter the !Config file within the !DeskStart
directory. The !Config file is read every time that !DeskStart is started.

All values which may be specified in the !Config file have defaults within
the main program which are used if no command redefined them. If a command
occurs more than once, the one which occurs last in the file is used. Note
that any unrecognised command in the !Config file is simply ignored, and the
last valid command (or default is used). This means that any string which
does not match a command may be used to start comment lines, but also that
mistyped commands will not be noticed.

The parameters of a command start from the first non-space character after
the command, and continue to the end of the line (or file). This means that
for string parameters, leading spaces are ignored, but trailing spaces are
included - be careful, it is very easy to leave a space character on the end
of a line without noticing it.

The valid configuration commands are:

    NoAutoWrite: The presence of this command prevents the production of
timings files. There is no command to turn the creation of timings files back
on - just the absence of this command. One possible use of this command is to
create a timings file, edit it to adjust timings, and then prevent the edited
version from being altered.

    NoLockedWarning: The presence of this command suppresses the warning
which is produced if the timings file is locked - it simply does not create a
timings file under these conditions. If no timings file exists, or the
timings file is not locked, a new one is created as usual. As for
NoAutoWrite, there is no opposite to this command, merely the absence of it
from the !Config file.

    TimeToPoll: The presence of this command causes timing of commands to
last until the next Wimp_Poll null, instead of just until the WimpTask
command finishes. Again, as for NoAutoWrite, there is no opposite to this
command, merely the absence of it from the !Config file.

    PrefixNoEcho <s>, PrefixInternal <s>, PrefixComment <s>: These commands
change the special characters used to start comments, internal commands, and
to prevent internal commands being echoed. The default values are "@", "%"
and "|" respectively. All the values start with the first displayable
character, and may contain any number of extra characters (which may include
spaces). In general the prefixes should be defined so that no prefix can form
the start of any other prefix. The one exception to this rule is that the
prefix for a comment may be defined as a sub-string of either of the other
two prefix types. This allows (for example) an internal command to start with
"|%", and a comment to start with "|".

It is also possible to change some of the text displayed by the program. This
is done by editing the Messages file. It is important that the tokens are
kept the same, only the messages are changed. The reason for wishing to alter
the messages is to change the language if the program is being used in a
different country. If you do translate the messages into any other
language(s), please send me a copy so that it may be included as an option in
future versions.

The default position of the status window may be changed by loading the
Templates file into a window template editor (e.g. !FormEd or !WindowEd) and
moving the Status window to the required position. It is better to include an
OpenAt command in the DeskStrt file than to perform this change, as the
templates are liable to change in future versions of the software.

There are currently three designs of template files supplied with this
program:
    TemplA43D: Smaller status window to take up less of the A4 portable
screen.
    TemplOld3D: Old style 3D templates with raised (ridge) group border
icons.
    TemplNew3D: New style 3D templates with sunken (channel) group border
icons.

Copy the desired templates file over the existing Templates file.

Errors
~~~~~~
There are two kinds of errors deliberately generated by this this program.
The first type causes a standard WIMP error box to be produced, followed by
the program quitting. This normally occurs if the program has been called
wrongly, e.g. without specifying the name of a DeskStrt file.

The other kind of error produced by !DeskStart is shown in the status window.
This happens if there is an error in the DeskStrt file (normally with
internal commands). Execution of the file is halted.

If an error is generated by any of the commands passed to WimpTask, a
standard WIMP error box will be produced, but !DeskStart should continue
normally afterwards.

Unforeseen errors normally include an internal error code in the message, and
should be reported to the author (see below).

Acknowledgements
~~~~~~~~~~~~~~~~
Thanks to:
    Simon Huntington: Interface module.
    Martin "MAD" Dorey: Testing this program, numerous ideas and suggestions.
    Dominic Symes: The brilliant Zap text editor - highly recommended.
    Mark Wooding: WindowEd 1 and 2, Glass, advice.
    Michael Ben-Gershon: Requesting an Iyonix compatible version.
Finally thanks to all at the Acorn User Group in Oxford.

Finally
~~~~~~~
The author would, of course, be interested in hearing of any bugs or any
other unexpected features, and will endeavour to correct any such bugs in any
future releases of this software. Suggestions for improved features are also
most welcome. Implementation depends on practicability and, more importantly,
the author's spare time.

If you have any comments on this program, or would like to suggest ways in
which it could be improved, then the author can be contacted directly by one
of the following means:

Snail-mail: 6 Tenison Manor
            Cottenham
            Cambridge
            CB4 8XL

E-mail:     alex@thouky.co.uk

If in any communication you make specific reference to the program code please:
    (i)   quote the version number and date,
    (ii)  refer only to the program as released,
    (iii) supply as many details as possible about the problem, including the
hardware and software configuration of the machine being used.

Please send a stamped and self addressed envelope, or give details of how to
contact via e-mail, if you require a reply.

I hope you find the program of some use.

Update list
~~~~~~~~~~~
v1.00 original prototype
v1.01 complete rewrite, new format for timings file, status window added
v1.02 single stepping added, percentage completed bar display, removed use of hourglass, internal commands in DeskStrt file
v1.03 alias for *Desk added, automatic update of Program Information window, other minor corrections
v1.04 key presses mimic clicks on icons
v1.05 menu implemented
v1.06 author information added, and menu debugged
v1.07 corrections to template file
v1.08 increased number of commands allowed
v1.09 faster icon added
v1.10 abort icon not activated by Return, handling of timings file improved
v1.11 Interface v2.00 used
v1.12 added ability to change string to start comments and internal commands, speed command added
v1.13 !Config file added, options for creation of timings files, tidied command handling, extra file checking, MessageTrans used for text
v1.14 MessageTrans used for menus
v1.15 loading of modules improved
v1.16 added option to time until next Wimp_Poll null
v1.17 new templates designed
v1.18 !Help updated and spelling errors corrected
v1.19 official filetype allocation used, small templates for A4
v1.20 InterfaceManager not used on RISC OS 4 and later
